fix(build): emit spec .d.ts in program order so two builds of one sha match byte for byte - #30131

Requested by Yibo Wang · project thread

Part of #30061 (the seat closes the card on landing; a claude/project-thread-* branch cannot satisfy check:closing-target-claim).

维护者速读

• 改了什么：tsup 补丁里的 rollup-plugin-dts 改为在 rollup 读取任何模块之前，按 ts.Program 自身的文件顺序把每个源文件的 .d.ts 一次性生成好；另加一个 pin 测试。spec 源码与 schema 一行未动。
• 为什么改：同一份 main 源码构建两次，spec 的 134 个 .d.ts 中有 18 个字节不同（含 chunk 文件名），拆分大文件的 PR 因此只能两两配对读声明证据。根因是生成顺序跟着 rollup 的异步加载顺序走，每次都不一样。
• 风险与回滚：补丁作用于仓内所有走 tsup DTS 的包；每个文件仍只生成一次，spec 的 DTS 耗时 44s 不变。修复后的产物与 main 已经会产出的两种状态之一逐字节相同。回滚 = revert 本 PR（补丁、锁文件哈希一起回）。
• 先看：patches/tsup@8.5.1.patch（新增的 emitInProgramOrder 与 transform 钩子里的读取）；packages/spec/scripts/dts-emit-order.pin.test.ts；packages/spec/tsup.config.ts 中改写的文档块。
• 两分钟验证：pnpm --filter @objectstack/spec exec vitest run --project local scripts/dts-emit-order.pin.test.ts，预期 2 个测试通过，约 5 秒。
• 需要你做的：无，席位落地。

Clause-②: no
Metadata-protocol: none

What changes

The cause. @objectstack/spec's DTS pass runs every entry through one ts.Program (the existing tsup patch). Its checker creates each type once, on first use, and TypeScript prints union members, and the object members derived from them, in type-creation order. tsup's bundled rollup-plugin-dts emitted each file's declarations inside rollup's transform hook, so whichever file rollup transformed first created the shared literal types and fixed the member order of every later file. Rollup transforms in the order its async fs.promises.readFile loads finish, which changes from run to run. Measured: in two DTS passes of one tree the transform order differed at 389 of 445 positions, starting with the first module.

The parallel-build suspect does not hold. tsup runs the DTS pass as ONE rollup build in one worker, transforms each module once, and writes the esm and cjs outputs from that one module graph. The .d.ts and .d.mts twins carry the same member order within a run. The order moves between runs, not between the formats.

The fix. patches/tsup@8.5.1.patch (regenerated with pnpm patch / pnpm patch-commit; the lockfile's patch_hash moves with it) adds emitInProgramOrder(program): on the first transform, it emits every non-declaration, non-external source file of the program once, in program.getSourceFiles() order, and stores each file's text and diagnostics. The transform hook then reads the stored text instead of emitting. Each file is still emitted exactly once, and the noEmitOnError error path is unchanged. The first hunk, which gives every entry one program, is unchanged.

Docs. packages/spec/tsup.config.ts's "NOT BYTE-STABLE" paragraph is rewritten: one tree now gives one set of bytes, but the order is the program's, so comparing two DIFFERENT sources still needs the order-insensitive reading. pnpm-workspace.yaml's note on the tsup patch gains the second change.

The pin. packages/spec/scripts/dts-emit-order.pin.test.ts (local project, ~4 s) builds a two-entry fixture through the real tsup CLI twice. A preload delays rollup's read of a.ts in one run and b.ts in the other, so the two runs transform the entries in opposite orders, and the test requires byte-equal output (.d.ts and .d.mts). Two controls: the fixture is order-sensitive under this TypeScript (a hand emit in the two orders gives "zeta" | "alpha" | "mid" and "mid" | "alpha" | "zeta"), and each run's read log shows the forced order reached rollup.

Why a fixture and not two full builds in CI: one spec DTS pass is ~45 s and ~3.5 GB RSS, and of four unforced builds of main, three agreed byte for byte. Two full builds would double the cost and still miss a regression most of the time. The forced order fails on every run.

Its radius, measured: a commit changing only patches/tsup@8.5.1.patch and pnpm-lock.yaml makes turbo ls --affected report 131 packages, @objectstack/spec among them, and the root external-dependency hash is in turbo's global cache inputs. So a later tsup patch change re-runs this pin.

Changeset: skip-changeset. Nothing published changes. The post-fix spec declaration tree is byte-identical, 134/134, to one of the two trees main already builds (base1 below). tsup.config.ts, the test, patches/ and the lockfile are not in any files[].

Tests

• Pin: 2/2 pass. Ablation: with the installed rollup.js swapped for the pre-fix one (one-program hunk only), the byte-equality test fails (expected { …(4) } to deeply equal { …(4) }) and the order-sensitivity control still passes. Restored, sha256 checked equal to the fixed file.
• pnpm --filter @objectstack/spec test: exit 0, 812/812 files, 24397 passed, 1 todo.
• NODE_OPTIONS=--max-old-space-size=6144 pnpm --filter @objectstack/spec typecheck: exit 0.
• eslint --no-inline-config on the two touched TypeScript files: exit 0.

Acceptance notes

• The patch serves every package that builds declarations with tsup here (twelve have more than one DTS entry). Their declaration member order now follows their program order too. Equivalent types, possibly a different one of their existing run-to-run orders on their next release. NOT MEASURED per package: reason, outside this card's spec measurement; no published file of theirs changes in this PR.
• File surface: the claim named the spec d.ts build configuration under packages/spec. The rollup-plugin-dts behaviour lives in the root tsup patch, so the diff also touches patches/tsup@8.5.1.patch, pnpm-lock.yaml (the patch hash) and pnpm-workspace.yaml (comment only).
• A move-only split now reads from ONE base/head pair. Measured on refactor(spec): codemod split of conversions/registry.ts into per-entry modules (#29987) #29993's split: the tree with d79eecfe's packages/spec/src change reverted and the current tree gave 134/134 byte-identical declarations under the fix.
• The --dts check in scripts/codemod-split-*.mjs is untouched (Codemod split: put driver-sql sql-driver.ts into facade form with a deterministic script, like protocol.ts and engine.ts #30105 is in flight there).

Verification

Generated by Claude Code